home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Internet Tools 1995 April / Internet Tools.iso / infoserv / gopher / Unix / GopherTools / jughead / jughead.ReadMe < prev    next >
Encoding:
Text File  |  1994-11-21  |  12.9 KB  |  354 lines
  1. Copyright 1993, 1994, University of Utah Computer Center.
  2. JUGHEAD (TM) is a trademark of Archie Comic Publications, Inc.
  3. and is used pursuant to license.  This source may be used and
  4. freely distributed as long as this copyright notice remains
  5. intact, and is in no way used for any monetary gain, by any
  6. institution, business, person, or persons.
  7.  
  8. jughead is a tool for getting menu information from various gopher
  9. servers, acting as a search engine in a specified gopher sub-space,
  10. and is an acronym for:
  11.  
  12.     Jonzy's Universal Gopher Hierarchy Excavation And Display
  13.  
  14. The remainder of this document is divided into two parts, the first
  15. part titled "KNOWN PORTS" lists all machines jughead is known to
  16. have been ported to, and the second part "GETTING STARTED" is a
  17. somewhat detailed set of steps to assist you in getting jughead up
  18. and running.
  19.  
  20. ----------------------------------------------------------------------
  21. KNOWN PORTS
  22.  
  23. jughead was written in ANSI C, developed on both an IBM RS6000, and
  24. a Sun sparc-10, and should port easily to any ANSI C conformant
  25. environment.  jughead has been successfuly ported to the following
  26. platforms:
  27.  
  28.     Apple Macintosh IIci with a A/UX 3.0
  29.  
  30.     DEC VAX/VMS version 5.5-1 running multinet networking software
  31.  
  32.     DECstation 5000/25 running Ultrix 4.2a
  33.  
  34.     DECstation 5000/200 running Ultrix 4.2
  35.  
  36.     DECstation 5000/200, Ultrix 4.3
  37.  
  38.     DECstation 5000/240, ULTRIX 4.4
  39.  
  40.     Dec 5000, running Ultrix 4.2A
  41.  
  42.     Digital DECstation 5000, model 133
  43.  
  44.     DEC 5900 running ULTRIX V4.3A
  45.  
  46.     HP-UX oac3 A.09.03 E 9000/750 2011779154
  47.  
  48.     HP 9000/815 running HP-UX version 9.0
  49.  
  50.     Hewlett-Packard 9000/730 with HP-UX 8.07
  51.  
  52.     Hewlett-Packard 9000/822 with HP-UX 8.07
  53.  
  54.     IBM RISC/6000 520H running AIX 3.2.3
  55.  
  56.     IBM RS/6000 950 running AIX 3.2.4
  57.  
  58.     insey Computer Systems model FS-486/50-SCO-64.1250.14LR",
  59.     476-90-4049 Tower Microcomputer running SCO Open Server Enterprise
  60.     System 3.2v4.2
  61.  
  62.     icronics 486-66, 2 - IDE drives, Linux 1.0
  63.  
  64.     NeXT 040 running NeXTSTEP 2.1
  65.  
  66.     NeXT 040 running NeXTSTEP 3.0
  67.  
  68.     SCO
  69.  
  70.     Sun SPARCstation IPC with SunOS 4.1.1
  71.  
  72.     SUN Sparc-2, Sun-OS 4.1.2
  73.  
  74.     Sun sparc4 running sun OS 4.1.2
  75.  
  76.     Sun Sparc1+ compatible (Aeon1+), SunOS 4.1.3
  77.  
  78.     Sun 4/690 running SunOS 4.1.1
  79.  
  80.     Sun 6/70 MP running SunOS 4.1.2
  81.  
  82.     Sun SPARCstation 1 under SunOS Release 4.1.2
  83.  
  84.     SunOS sun09 4.1.3 1 sun4c
  85.  
  86.     SUN SparCentre 2000 running Solaris 2.3
  87.  
  88.     Viglen 486DX33 16Mb RAM running FreeBSD 1.0.2
  89.  
  90. It is anticipated this program will be a tool for administrators
  91. in gopherspace.  If you make any changes to the sources, please
  92. send me a copy.  <jonzy@cc.utah.edu>
  93.  
  94. ----------------------------------------------------------------------
  95. GETTING STARTED
  96.  
  97. jughead can be acquired via gopher by gophering to gopher.utah.edu
  98. and looking in:
  99.    About U of U Gopher
  100.       Gopher Tools
  101.          jughead
  102.             as jughead.ReadMe and jughead.VERS.tar.Z
  103. or via anonymous ftp from ftp.cc.utah.edu in /pub/gopher/GopherTools/jughead
  104. as jughead.ReadMe and jughead.VERS.tar.Z, where "VERS" is the current version.
  105.  
  106. Once you have downloaded jughead the following command will uncompress and
  107. untar the files into a directory that gets created called "jughead.VERS":
  108.     uncompress -c < jughead.VERS.tar.Z | tar xfv -
  109.  
  110. The file jughead.VERS.tar.Z is a compressed tar file which contains:
  111.     About.jughead
  112.     Makefile.dist
  113.     configure
  114.     dirTree.c
  115.     dirTree.h
  116.     getargs.c
  117.     jughead.1
  118.     jughead.ReadMe            THE FILE YOU ARE READING NOW
  119.     jughead.c
  120.     jughead.changes
  121.     jughead.conf
  122.     jughead.conf.5
  123.     jughead.conf.h.dist
  124.     jughead.faq
  125.     jughead.h
  126.     jughead.sample.csh
  127.     jughead.survey
  128.     jughead.todo
  129.     jugheadConf.c
  130.     jugheadVctl.c
  131.     path.c
  132.     search.c
  133.     searchCmnds.c
  134.     sockets.c
  135.     sockets.h
  136.     tree.c
  137.     tree.h
  138.     utils.c
  139.     utils.h
  140.     veronica.ctl
  141.     veronica.ctl.5
  142.  
  143. For a quick compilation attempt do the following:
  144.    cd jughead.VERS
  145.    configure        (At the prompt, hit return to make jughead)
  146.    edit jughead.conf    (To get the file ready for the next step)
  147.    make install        (If errors, are you root?  If not simply
  148.             comment out the Makefile install target lines
  149.             cp jughead.1 $(DESTMAN)/jughead.$(MANSUFF)
  150.             chown root $(DESTMAN)/jughead.$(MANSUFF)
  151.             chmod 755 $(DESTMAN)/jughead.$(MANSUFF)
  152.             cp veronica.ctl.5 $(VDESTMAN)/veronica.ctl.$(VMANSUFF)
  153.             chown root $(VDESTMAN)/veronica.ctl.$(VMANSUFF)
  154.             chmod 755 $(VDESTMAN)/veronica.ctl.$(VMANSUFF)
  155.             and change DESTDIR to the current directory)
  156.  
  157.  
  158. To make the jughead application do a "configure" which will do some
  159. configuring for your environment and generate jughead.conf.h, Makefile,
  160. and sprint.h headerfile.  If "configure" was able to determine the local
  161. configuration for your platform correctly it will ask you if it should
  162. run "make" for you.  The configuration file is known to correctly on
  163. the following platforms determined from the `uname -mrsv` system call:
  164.     4.3bsd 2.0 B 9000/375
  165.     AIX 2 3 000007401C00
  166.     A/UX 3.0 SVR2 mc68040
  167.     HP-UX A.08.00 B 9000/845
  168.     HP-UX A.09.00 D 9000/850
  169.     IRIX 4.0.5 06151813 IP6
  170.     IRIX 5.1.1.2 11021902 IP22
  171.     Linux 1.1.0 #1 Tue May 31 15:42:59 MDT 1994 i386
  172.     openage 2 3.2 i386
  173.     SunOS 4.1.3 2 sun4
  174.     SunOS 4.1.3 1 sun4m
  175.     SunOS 5.1 Generic sun4m
  176.     ULTRIX 4.4 0 RISC
  177. And machines without `uname -mrsv':
  178.     NeXT 2.1
  179.     NeXT 3.0
  180.     NeXT 3.1
  181.     NeXT 3.2
  182.  
  183. Every effort has been made with the configure script to ease the pain
  184. of porting jughead.  If you run into any problems please let me know so I
  185. can modify the configure script to accommodate your particular platform.
  186.  
  187. At this point you may want to read the jughead.changes file which lists
  188. the development changes to jughead, and the jughead.todo file which lists
  189. the things still needing attention.
  190.  
  191. You do not need to have root access to install or run jughead, you will,
  192. however, need to ensure DESTDIR and DESTMAN in the Makefile are adjusted
  193. to reflect your particular needs.
  194.  
  195. To view the man page, prior to running make install you can:
  196.     make viewman
  197.  
  198. The make commands supported by the jughead Makefile are:
  199.  
  200.    make            makes jughead.
  201.    make all        same as make.
  202.    make jughead        same as make.
  203.    make objects        compiles the various jughead sources.
  204.    make install        same as make, intalls jughead the man page,
  205.             and the jughead.conf file.
  206.    make clobber        same as realclean and removes the installed files.
  207.    make realclean    same clean and removes sprint.h, Makefile.config,
  208.             and the jughead executable.
  209.    make clean        removes the objects, core and backup edit files.
  210.    make tar        tars and compresses all files except jughead.ReadMe
  211.    make viewman        allows viewing the man page prior to installation.
  212.    make lint        runs lint to report on the programmers codability.
  213.    make help        displays the various make options.
  214.    make defunct        same as make but forces recompilation of search.o
  215.    make nodefunct    same as make except code is generated to remove the
  216.             <defunct> process which will result in a cleaner
  217.             environment, but produce less efficient code.
  218.  
  219. It is highly recommended you edit the "jughead.conf.h" file to ensure
  220. the defines HOSTDOMAIN, JUGHEADHELP, and ERRORHOST reflect the needs
  221. for your site.  These values can be overridden if you edit the "jughead.conf"
  222. file and ensure "hostname", "jugheadhelp", and "errorhost" reflect your site
  223. as well.
  224.  
  225. If you have problems compiling look at the Makefile and sprint.h files
  226. created via "configure".  Alternatily you may need to look at the
  227. jughead.conf.h and Makefile.
  228.  
  229. The following information describes the purpose of various defines and
  230. variables to assist you should any problems be encountered:
  231.  
  232.   These values are found in jughead.conf.h:
  233.   You can use the jughead.conf file alter these values. 
  234.   HOSTDOMAIN      Any part of your machine name that does not get displayed
  235.           via a call to `hostname`.  The result of `hostname` and
  236.           HOSTDOMAIN should yield a fully qualified domain name of the
  237.           machine running jughead.
  238.           Note: The fully qualified domain name can be overridden by
  239.           entering "hostname" as the name in the jughead.conf file.
  240.   JUGHEADHELP     The gopher server serving the jughead help document.
  241.           This is the gopher selector, host, and port of the document
  242.           to give the user if an error is encountered.
  243.           Note: This field can be overridden by entering "jugheadhelp"
  244.           as the gopher path to the jughead help document in the
  245.           jughead.conf file.
  246.   ERRORHOST       The Path, Host, and Port for an error item.
  247.           Note: This field can be overridden by entering "errorhost"
  248.           as the gopher path in the jughead.conf file.
  249.   PORT2USE        The port to use when jughead is a search engine.
  250.   MAXPROCS      The maximum number of forked jughead processes.
  251.   DELIMITERS      The delimiters that seperate a word.
  252.   MAXITEMS2RETURN The maximum number of found items to return.
  253.   DEFAULTBOOLOP   The default boolean operator if none is given between words.
  254.   JUGHEADHELPTITL The title to be displayed to the user of the jughead
  255.                   help document.
  256.   USAGERROR       The string "usage error".
  257.   WILDCARDERR     The invalid wildcard usage error message.
  258.   TOMNYPRCSERR    The too many processes error message.
  259.   NOFORKERR       The jughead can't fork error message.
  260.   GTSTRERR        The get string timed out error message.
  261.   READERR         The read line error message.
  262.   TMPFILENAME     The location and name of jughead's temporary file.
  263.  
  264.   These values are found in jughead.conf.h are automaticly generated when you
  265.   run "configure".  These too can be altered via the jughead.conf file.
  266.   CATCOMMAND      The cat system command, the %s is required.
  267.   SORTCOMMAND     The sort system command, the %s is required.
  268.   TOUCHCOMMAND    The touch system command, the %s is required.
  269.  
  270.   These values are found in Makefile
  271.   THEVERSION      The version of jughead, only edit this if you make changes.
  272.   MANSUFF         The suffix of the man page and where to install the manpage.
  273.   DESTDIR         The location of the jughead executable.  You may not want
  274.           this to be publicly accessible.
  275.   DESTMAN         The location of the jughead man page.
  276.   PERMISSIONS     The permissions for the jughead executable.
  277.   LINT            The lint program to use if need me.
  278.   LINTFLAGS       Any lint flags you want to set.
  279.   CC              The C compiler to use.  Note: You can leave this blank
  280.           if you don't know where your C compiler resides, the
  281.           configuration step will attempt to locate it for you.
  282.   NOWARNINGS      Uncommented if you don't want to see any compiler warnings.
  283.   OPTIMIZATION      Any optimization flags you want to have.
  284.   PROTOTYPES      Uncommented if you want to use prototypes.
  285.  
  286.   These values are found in Makefile are automaticly generated when you
  287.   run "configure".  If you know you need these flags simply add them to the
  288.   DFLAGS or LFLAGS line.
  289.   -D_POSIX_SOURCE    Needed when compiling under A/UX.
  290.   -DSOLARIS2 -DSVR4  Needed when compiling on a sun with Solaris.
  291.   -lsocket -lnsl     Needed for linking under Solaris
  292.   DFLAGS         The definition flags needed for your environment
  293.   CFLAGS         The compiler flags needed for your environment.
  294.   LFLAGS         The libraries you need, some libraries may exist
  295.              here you don't need but this should not cause
  296.              problems.
  297.  
  298. You will want to place the "About.jughead" document somewhere on your
  299. gopher server, and then give the proper definition of JUGHEADHELPDOC
  300. in the jughead.conf.h or "jugheadhelp" in jughead.conf.  You may want
  301. to copy the file "About.jughead" in the same directory as the jughead
  302. link, so the users will have knowlege of how to search the tables built
  303. by jughead, and rename it "About jughead".
  304.  
  305. Create a link file somewhere in your gopher data directory.  Mine looks like:
  306.   Name=Search all UofU menus using jughead
  307.   Numb=4
  308.   Type=7
  309.   Port=3000
  310.   Path=
  311.   Host=gopher.utah.edu
  312.  
  313. As of jughead version 1.0.3 you can assist veronica in harvesting its
  314. data by configuring and placing the veronica.ctl file, included with
  315. this distribution, at the appropriate location in your gopher tree.
  316.  
  317. IMPORTANT NOTE:  jughead does NOT use aliased hostnames and requires
  318. Fully Qualified Domain Names.
  319.  
  320. The steps I did to get jughead running as a server follow:
  321.  jughead -tmVb data -X "ftp:*" .utah.edu gopher.utah.edu
  322.  jughead -tB data
  323.  jughead -tS -l data.log data
  324.  
  325. Sample steps to rebuild the jughead database follow:
  326.  cd directory_other_than_where_the_jughead_data_resides
  327.  jughead -b data -l report -X "ftp:*" .utah.edu gopher.utah.edu
  328.  jughead -B data
  329.  mv data* directory_where_the_jughead_data_resides/
  330.  kill -HUP `/usr/ucb/head -1 /usr/local/etc/jughead.pid`
  331.  
  332. Edit the jughead.sample.csh script to meet your particular needs.  This
  333. script is a sample script to be used by cron.
  334.  
  335. There are more examples of jughead commands listed in the man page.
  336.  
  337. NOTE: jughead is not inetd compatible.  Furthermore, if you note any
  338. problems building the database you should ensure that gopherd is NOT
  339. run via inetd.
  340.  
  341. There exists a mailing list for discussion about jughead called:
  342. jughead-news@lists.utah.edu    To get on this mailing list send
  343. mail with the subject "subscribe", without the quotes to:
  344.    jughead-news-request@lists.utah.edu
  345.  
  346. Please take the time to fill out the jughead.survey and return it to me.
  347.  
  348. Please email source changes, compliments, complaints, or suggestions to:
  349.  
  350.     Rhett "Jonzy" Jones
  351.     jonzy@cc.utah.edu
  352.  
  353. I hope you find jughead a useful tool.
  354.